Run batch regressions across multiple DVs and datasets

The main entry point for fittr. Takes a set of base model specifications and a list of definitions describing DVs, regression functions, and optional extras, then runs all combinations in parallel.

Usage

fit_models(
  models,
  data,
  defs,
  weight_var = NULL,
  weighted_only = FALSE,
  workers = NULL,
  plan = future::multisession,
  furrr_opts = furrr::furrr_options()
)

Arguments

models

A named list of model_spec objects, one per model to run. Names become the keys in the returned results list.

data

A data frame, or a named list of data frames. When a list is provided, every model is run once per dataset.

defs

A named list of definition lists. Each element must contain:

dv

Character. The dependent variable name.

fun

Function (or named list of functions) with signature f(formula, data, weights), or a character string naming a function (e.g. "lm" or "fixest::feols"). A string is wrapped into function(f, d, w, ...) <fun>(f, data = d, weights = w, ...), The formula is passed as the first argument, whatever that argument is called. Arguments set with set_args are passed as further named arguments, so a function fitting such a model needs ... or arguments of those names.

and may optionally contain:

extra_terms

Character vector of terms appended to every model's main terms (but not to its parts; see set_parts) for this DV only.

additional_models

Named list of model_spec objects added to the model set for this DV only.

model_mods

Named list of functions of the form function(model_spec) -> model_spec. Each entry modifies the named base model for this DV only, leaving other DVs unchanged.

weight_var

Character. Name of a column in data to use as regression weights. When supplied, each model is run twice: once unweighted and once weighted. Default NULL (no weights).

weighted_only

Logical. When TRUE and weight_var is supplied, only the weighted variants are run. Default FALSE.

workers

Positive integer or NULL (default). When provided, fittr calls future::plan(plan, workers = workers) internally, dispatches all runs (all DVs \(\times\) models \(\times\) datasets \(\times\) weights) in a single parallel furrr::future_pmap call, then restores the previous plan on exit. When NULL, DVs are processed sequentially and within-DV parallelism uses whatever future::plan() the caller has already set.

plan

A future strategy passed to future::plan() when workers is not NULL. Defaults to future::multisession (new background R sessions, works on all platforms). Other options include future::multicore (forked processes, Unix/macOS only, lower overhead) or future::cluster (pre-existing worker cluster). Ignored when workers = NULL.

furrr_opts

A furrr_options object controlling furrr behaviour (seed, packages, globals, scheduling, etc.). Passed as the .options argument to future_pmap. Default furrr::furrr_options().

Value

A list (one element per definition) of named lists. Each inner list has names of the form "model.dataset.weights" (components are omitted when there is only one dataset or no weighting).

See also

model_spec, preview_fit

Examples

base_m <- model_spec(cyl, disp)

models <- list(
  base     = base_m,
  ext      = base_m |> add_terms(hp),
  base_int = base_m |> add_interaction(cyl, disp)
)

data_sets <- list(all = mtcars, high_mpg = mtcars[mtcars$mpg > 20, ])

defs <- list(
  mpg = list(
    dv  = "mpg",
    fun = "lm",
    # Remove disp from the extended model for mpg only
    model_mods = list(ext = \(m) drop_terms(m, disp))
  ),
  carb = list(
    dv  = "carb",
    fun = function(f, d, w) stats::lm(f, d, weights = w)
  )
)

results <- fit_models(models, data_sets, defs)